<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
    <html>
    <head>
    <title></title>
    <link rel="stylesheet" type="text/css" href="stx.css" media="screen" title="screen">
    </head>
    <body>
<h1 id='h1.0'>Structured Text</h1>

 
<pre>Written by Colin McCormack &lt;colin@chinix.com&gt;.  April 2005.</pre>

 
<p>Structured text is a wiki-inspired format to specify html (and other) documents.</p>
 
<hr style='clear:both;'> 
<table class='TOC'>
<thead><tr><td colspan='2'>Table Of Contents</td></tr></thead><tbody><tr><td class='TOCnum'><a href='#h1.0'>1</a></td> <td>Structured Text</td>
</tr><tr><td class='TOCnum'><a href='#h2.0'>1.1</a></td> <td>Paragraph Features</td>
</tr><tr><td class='TOCnum'><a href='#h3.0'>1.1.1</a></td> <td>Lists</td>
</tr><tr><td class='TOCnum'><a href='#h4.0'>1.1.1.1</a></td> <td>Unordered List Example:</td>
</tr><tr><td class='TOCnum'><a href='#h5.0'>1.1.1.2</a></td> <td>Ordered List Example:</td>
</tr><tr><td class='TOCnum'><a href='#h6.0'>1.1.1.3</a></td> <td>Nested List Examples:</td>
</tr><tr><td class='TOCnum'><a href='#h7.0'>1.1.2</a></td> <td>Definition Lists</td>
</tr><tr><td class='TOCnum'><a href='#h8.0'>1.1.2.1</a></td> <td>Definition List Example:</td>
</tr><tr><td class='TOCnum'><a href='#h9.0'>1.1.3</a></td> <td>Preformatted Paragraphs</td>
</tr><tr><td class='TOCnum'><a href='#h10.0'>1.1.3.1</a></td> <td>Preformatted Paragraph Example:</td>
</tr><tr><td class='TOCnum'><a href='#h11.0'>1.1.4</a></td> <td>Headers</td>
</tr><tr><td class='TOCnum'><a href='#header_example'>1.1.4.1</a></td> <td>Header Example:</td>
</tr><tr><td class='TOCnum'><a href='#h12.0'>1.1.5</a></td> <td>Horizontal Rule</td>
</tr><tr><td class='TOCnum'><a href='#h13.0'>1.1.5.1</a></td> <td>Horizontal Rule Example:</td>
</tr><tr><td class='TOCnum'><a href='#h14.0'>1.2</a></td> <td>Character Features</td>
</tr><tr><td class='TOCnum'><a href='#h15.0'>1.2.1</a></td> <td>Typefaces</td>
</tr><tr><td class='TOCnum'><a href='#h16.0'>1.2.2</a></td> <td>References</td>
</tr><tr><td class='TOCnum'><a href='#h17.0'>1.2.3</a></td> <td>URL forms</td>
</tr><tr><td class='TOCnum'><a href='#h18.0'>1.2.4</a></td> <td>Images</td>
</tr><tr><td class='TOCnum'><a href='#h19.0'>1.2.4.1</a></td> <td>Image Examples</td>
</tr><tr><td class='TOCnum'><a href='#h20.0'>2</a></td> <td>Relaxed Interpretation</td>
</tr><tr><td class='TOCnum'><a href='#h21.0'>3</a></td> <td>Implementation</td>
</tr><tr><td class='TOCnum'><a href='#api'>3.0.1</a></td> <td>STX translation API</td>
</tr><tr><td class='TOCnum'><a href='#h22.0'>3.1</a></td> <td>Source</td>
</tr><tr><td class='TOCnum'><a href='#h23.0'>3.1.1</a></td> <td>Changelog</td>
</tr></tbody></table>


 
<hr style='clear:both;'> 
<h2 id='h2.0'>Paragraph Features</h2>

 
<p>A paragraph is represented as a sequence of lines terminated by a blank line.</p>
 
<hr style='clear:both;'> 
<h3 id='h3.0'>Lists</h3>

 
<p>Ordered and Unordered lists (and all nested variants thereof) are specified by a sequence of paragraphs beginning with some sequence of the characters
 '#' and '*'.</p>
 
<p><span style='font-weight: bold;'>Note:</span> as a special case, a list paragraph may run directly on from preceding list paragraphs (that is, without an intervening blank line.) This is for the convenience of authors and to improve document density.</p>
 
<hr style='clear:both;'> 
<h4 id='h4.0'>Unordered List Example:</h4>

 
<ul>
<li>Unordered lists are comprised of paragraph beginning with '*'


</li>
<li>a non-list paragraph terminates the list.


</li>
<li>unordered lists may nest, and may be nested


</li>
</ul>
 
<p>The above text was generated by:</p>
 
<pre>* Unordered lists are comprised of paragraph beginning with '*'
* a non-list paragraph terminates the list.
* unordered lists may nest, and may be nested</pre>

 
<hr style='clear:both;'> 
<h4 id='h5.0'>Ordered List Example:</h4>

 
<ol>
<li>Ordered lists are comprised of paragraph beginning with '*'


</li>
<li>a non-list paragraph terminates the list.


</li>
<li>Ordered lists may nest, and may be nested


</li>
</ol>
 
<p>The above text was generated by:</p>
 
<pre># Ordered lists are comprised of paragraph beginning with '*'
# a non-list paragraph terminates the list.
# Ordered lists may nest, and may be nested</pre>

 
<hr style='clear:both;'> 
<h4 id='h6.0'>Nested List Examples:</h4>

 
<ul>
<li>Unordered lists may include nested lists

<ul>
<li>Nested lists may be unordered lists


</li>
<li>Such as this list, which begins with '**'

<ul>
<li>Nesting may continue to an arbitrary depth


</li>
</ul>

</li>
</ul>
<ol>
<li>Unordered lists may contain ordered lists


</li>
<li>Such as this list, which begins with '*#'


</li>
</ol>

</li>
<li>nested lists are compact


</li>
</ul>
 
<p>The above text was generated by:</p>
 
<pre>* Unordered lists may include nested lists
** Nested lists may be unordered lists
** Such as this list, which begins with '**'
*** Nesting may continue to an arbitrary depth
*# Unordered lists may contain ordered lists
*# Such as this list, which begins with '*#'
* nested lists are compact</pre>

 
<ol>
<li>Unordered lists may include nested lists

<ol>
<li>Nested lists may be unordered lists


</li>
<li>Such as this list, which begins with '##'

<ol>
<li>Nesting may continue to an arbitrary depth


</li>
</ol>

</li>
</ol>
<ul>
<li>Unordered lists may contain ordered lists


</li>
<li>Such as this list, which begins with '#*'


</li>
</ul>

</li>
<li>nested lists are compact


</li>
</ol>
 
<p>The above text was generated by:</p>
 
<pre># Unordered lists may include nested lists
## Nested lists may be unordered lists
## Such as this list, which begins with '##'
### Nesting may continue to an arbitrary depth
#* Unordered lists may contain ordered lists
#* Such as this list, which begins with '#*'
# nested lists are compact</pre>

 
<hr style='clear:both;'> 
<h3 id='h7.0'>Definition Lists</h3>

 
<p>Definition lists are specified as they are in <a href='http://wikipedia.org/'>http://wikipedia.org/</a> formatting language</p>
 
<ul>
<li>Definition lists are represented as a paragraph with leading ';'


</li>
<li>a ':' separates the <span style='font-style: italic;'>defined term</span> from its <span style='font-style: italic;'>definition</span>


</li>
</ul>
 
<h4 id='h8.0'>Definition List Example:</h4>

 
<dl><dt>Definition List</dt>
<dd>a list comprised of pairs of terms and definitions</dd>

<dt>Term</dt>
<dd>a thing to be associated with a definition</dd>

<dt>Definition</dt>
<dd>a thing which describes a term.</dd>

<dt>Circular Definition</dt>
<dd>this.</dd>

<dt>Putative Definition</dt>
<dd>a definition which only appears to define.</dd>

<dt>Ostensive Definition</dt>
<dd>a putative definition by example.</dd>
</dl>
 
<p>The above text was generated by:</p>
 
<pre>;Definition List : a list comprised of pairs of terms and definitions
;Term : a thing to be associated with a definition
;Definition : a thing which describes a term.
;Circular Definition: this.
;Putative Definition: a definition which only appears to define.
;Ostensive Definition: a putative definition by example.</pre>

 
<hr style='clear:both;'> 
<h3 id='h9.0'>Preformatted Paragraphs</h3>

 
<p>A paragraph comprised of lines which begin with a space character (' ')
 is not formatted in any way.</p>
 
<p><span style='font-weight: bold;'>Note:</span> a Simple Paragraph (one which is not a list, definition list, preformatted character, etc) must commence with a non-space character, but may have subsequent lines beginning with space.</p>
 
<h4 id='h10.0'>Preformatted Paragraph Example:</h4>

 
<pre>This paragraph will not be reformatted in any way.
Line breaks will be preserved.
* special characters have no meaning
* '''character level features''' and [references] are not interpreted.</pre>

 
<hr style='clear:both;'> 
<h3 id='h11.0'>Headers</h3>

 
<p>A header is represented as a paragraph which
 begins with some number of '=' characters.</p>
 
<p>The number of '=' characters in the paragraph prefix determines
 the <span style='font-style: italic;'>level</span> of the header.  Larger level headers are smaller.</p>
 
<p>Additionally, any text following subsequence (ie: <span style='font-style: italic;'>non-prefix</span>) '=' characters will be used to specify a <span style='font-style: italic;'>tag</span>, which (in the case of HTML translation) can be used as the local anchor of a link.</p>
 
<h4 id='header_example'>Header Example:</h4>

 
<p>The above (header) text was generated by:</p>
 
<pre>==== Header Example: ==== header_example</pre>

 
<hr style='clear:both;'> 
<h3 id='h12.0'>Horizontal Rule</h3>

 
<p>A horizontal rule is represented by a paragraph beginning with a '-'</p>
 
<h4 id='h13.0'>Horizontal Rule Example:</h4>

 
<p>The following horizontal rule was generated by:</p>
 
<pre>----</pre>

 
<hr style='clear:both;'> 
<h2 id='h14.0'>Character Features</h2>

 
<h3 id='h15.0'>Typefaces</h3>

 
<p>In addition to paragraph formatting, Structured Text provides for  character level features such as
 <span style='font-weight: bold;'>strong</span>, <span style='font-style: italic;'>italic</span>, <span style='text-decoration: underline;'>underlined</span>, <span style='text-decoration: line-through;'>strike through</span>, <span style='font-variant: small-caps;'>small caps</span>, <span style='vertical-align: super;'>superscript</span>, <span style='vertical-align: sub;'>subscript</span> and <span style='font-size: bigger;'>BIG</span> typefaces.</p>
 
<dl><dt>strong</dt>
<dd>is represented ''thus''</dd>

<dt>italic</dt>
<dd>is represented '''thus'''</dd>

<dt>strike through</dt>
<dd>is represented --thus--</dd>

<dt>underline</dt>
<dd>is represented __thus__</dd>

<dt>small caps</dt>
<dd>is represented %%thus%%</dd>

<dt>superscript</dt>
<dd>is represented ^^thus^^</dd>

<dt>subscript</dt>
<dd>is represented ^^^thus^^^</dd>

<dt>big</dt>
<dd>is represented !!thus!!</dd>
</dl>
 
<p><span style='font-weight: bold;'>Note:</span> combinations of the above are possible <span style='text-decoration: line-through;'><span style='text-decoration: underline;'><span style='font-variant: small-caps;'>thus</span></span></span></p>
 
<p><span style='font-weight: bold;'>Note:</span> The backslash character can be used to escape this special significance.</p>
 
<hr style='clear:both;'> 
<h3 id='h16.0'>References</h3>

 
<p>Anything within a paragraph which is contained in square brackets '&#91;' & '&#93;' is considered a link, or reference.</p>
 
<p>If the contents resembles a URL, subsequent contents are interpreted as descriptive text associated with the link.</p>
 
<p><span style='font-weight: bold;'>Note:</span> To avoid the special brace interpretation, double the braces, thus: &#91;&#91; and &#93;&#93;</p>
 
<hr style='clear:both;'> 
<h3 id='h17.0'>URL forms</h3>

 
<p>Anything within a paragraph which resembles a URL, (ie: that commences with <span style='font-weight: bold;'>http</span>:) will be turned into a Reference.</p>
 
<p>Additionally, &#91;#: name some text&#93; will be turned into an anchor suitable for local references.</p>
 
<p>Finally, &#91;acronym: <span style='font-weight: bold;'>term</span> | <span style='font-weight: bold;'>definition of term</span>&#93; will be turned into an html acronym.</p>
 
<hr style='clear:both;'> 
<h3 id='h18.0'>Images</h3>

 
<p>The reference style &#91;image:url&#93; can be used to insert an inline image in text.</p>
 
<p>The reference style &#91;left:url&#93; can be used to insert an inline image in text with left flow-around, so that the image is positioned to the left and any subsequent text flows around it.</p>
 
<p>The reference style &#91;right:url&#93; can be used to insert an inline image in text with right flow-around, so that the image is positioned to the right and any subsequent text flows around it.</p>
 
<h4 id='h19.0'>Image Examples</h4>

 
<p>This is the <img src='logo125.gif' class='image'  alt='logo125.gif' /> tcl logo inline.</p>
 
<p>This effect was generated by:</p>
 
<pre>This is the [image:logo125.gif] tcl logo inline.</pre>

 
<p><img src='logo125.gif' class='imageright'  style='float:right' alt='logo125.gif' /> <img src='logo125.gif' class='imageleft'  style='float:left' alt='logo125.gif' /> This paragraph has two tcl logos, one with left and one with right flow-around.</p>
 
<p><span style='font-weight: bold;'>Note:</span> Horizontal Rule clears the image flow-around.</p>
 
<p>This effect was generated by:</p>
 
<pre>[right:logo125.gif]
[left:logo125.gif]
This paragraph has two tcl logos, one with left and one with right flow-around.
</pre>

 
<hr style='clear:both;'> 
<h1 id='h20.0'>Relaxed Interpretation</h1>

 
<p>In many cases a paragraph may be terminated by the introduction of a special paragraph  formatting character on the first line of a subsequence line component, so the <span style='font-style: italic;'>blank line terminates a paragraph</span> rule is not absolutely enforced, however <span style='font-style: italic;'>header</span> lines must always be terminated by a blank line.</p>
 
<hr style='clear:both;'> 
<h1 id='h21.0'>Implementation</h1>

 
<p>An <span style='font-style: italic;'>stx2html.tcl</span> script is provided to give a sample of translating Structured Text
 to HTML.  It does nothing to prettify the text, leaving that to <a href='stx.css'>CSS</a>.</p>
 
<p>This documentation is written in <a href='stx.txt'>STX</a>, and converted by stx2html into HTML.</p>
 
<p>The script stx.tcl converts STX formatted text into a tcl script suitable for evaluation within a namespace which interprets a set of commands semantically, and which emit the appropriate translation as functional return values.</p>
 
<h3 id='api'>STX translation API</h3>

 
<p><span style='font-weight: bold;'>To Be Done</span>, meanwhile RTFS.</p>
 
<h2 id='h22.0'>Source</h2>

 
<p>The software should be available <a href='stx.tar.gz'>here</a>.</p>
 
<h3 id='h23.0'>Changelog</h3>

 
<dl><dt>21 Apr 2005</dt>
<dd>&#91;CMcC&#93; Released</dd>

<dt>22 Apr 2005</dt>
<dd>&#91;CMcC&#93; move content into cdata tree elements</dd>

<dt>22 Apr 2005</dt>
<dd>&#91;CMcC&#93; allow compacted lists (nested lists don't start a new LI)</dd>

<dt>22 Apr 2005</dt>
<dd>&#91;CMcC&#93; added .toc (table of contents)</dd>
</dl>
 


 
<!-- This is a comment {} -->


 


    </body>
    </html>

